fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

infiton · 2025-08-13T14:46:38Z

Description

This PR fixes an inconsistency in how browserHash values are set in depsOptimizer.metadata during the initial dependency scan, which can cause duplicate module instances to be loaded in the browser when the Vite dev server restarts mid–asset waterfall.

Background

At Gadget, we use Vite both for development (serving a React frontend) and for production builds. In development, each user works in an ephemeral environment (“sandbox”), which runs both:

A Vite dev server serving the frontend.
A Fastify backend server (also hosting the Vite dev server).

For frontend-only changes, the Vite server stays running and uses HMR to push updates to the browser.
For backend changes, however, we restart the entire Fastify process — which also restarts the Vite dev server.

These backend restarts are cheap and frequent, so developers often trigger them while the frontend is still loading in the browser.

The Problem

When a restart happens during the initial page load, we can hit the following sequence:

Cold boot: a new sandbox starts, and Vite builds dependency metadata (depsOptimizer._metadata.json) from scratch.
The first app request is served using this fresh metadata, and the browser begins fetching the asset waterfall (JS chunks, CSS, etc.).
Mid-load restart: the sandbox restarts while the browser is still fetching assets.
A new Vite server starts and loads the existing _metadata.json from disk (written in step 1).
Remaining asset requests in the waterfall are served from this second server.

Because browserHash in the in-memory metadata for the first server was not the same value eventually persisted to _metadata.json, the same dependency can be served with two different browser hashes across the restart.

If the dependency is React (or any library that maintains singleton state), this results in the browser having duplicate copies of the module, causing broken HMR, hydration errors, and subtle runtime issues.

Solution

This patch ensures that before resolving scanProcessing in the optimizer, we eagerly set the browserHash on the in-memory metadata to the value that will later be written to disk.

By doing this, both:

The first server (before writing to disk)
Any subsequent server (loading from _metadata.json)

will use identical browser hashes for the same dependency, as long as we wait for the initial scan to complete before resolving dependencies.

Why This Matters

Fixes a correctness issue that can manifest in real-world setups where Vite dev servers restart mid-load.
Ensures consistency between the in-memory and persisted metadata for dependencies.
Prevents hard-to-debug runtime errors caused by multiple versions of a singleton dependency being loaded into the same page.

infiton · 2025-08-18T13:59:03Z

cc @bluwy is there anything I need to do to get this into triage?

sapphi-red · 2025-08-21T12:07:19Z

Hmm, I think Vite expects all assets used in the same page to be loaded from the same Vite server instance (i.e. Vite server is not restarted during loading a page and the assets).

Mid-load restart: the sandbox restarts while the browser is still fetching assets.

A new Vite server starts and loads the existing _metadata.json from disk (written in step 1).

Remaining asset requests in the waterfall are served from this second server.

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

infiton · 2025-08-21T15:30:25Z

Vite expects all assets used in the same page to be loaded from the same Vite server instance

it makes sense that this would be an expectation, and I think there's a unique setup in Gadget that is exposing this issue where others probably haven't seen this ever

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

not necessarily; we see this happen the most frequently in react router SSR mode where the initial document is served and it loads some big modules like react and eventually it's hmr runtime which then loads the vite client (which then attempts to set up an hmr connection); if the server restarts while the hmr socket is trying to connect it can reject with:

Uncaught (in promise) Error: WebSocket closed without opened.
    at WebSocket.<anonymous> (client:454:22)

in ordinary situations the vite client will start polling for a reconnect, however in the meantime a duplicate copy of react loads and the page load crashes with

chunk-HUR6ZVB7.js?v=c5431c96:9255 TypeError: Cannot read properties of null (reading 'useContext')
    at Object.useContext (chunk-4S2OYCSJ.js?v=d029a2ac:1062:29)
    at useParams (chunk-HUR6ZVB7.js?v=d029a2ac:5464:28)
    at useErrorBoundaryProps (chunk-HUR6ZVB7.js?v=d029a2ac:6547:13)
    at WithErrorBoundaryProps2 (chunk-HUR6ZVB7.js?v=d029a2ac:6561:19)
    at renderWithHooks (chunk-ZSAHMUTT.js?v=c5431c96:11596:26)
    at mountIndeterminateComponent (chunk-ZSAHMUTT.js?v=c5431c96:14974:21)
    at beginWork (chunk-ZSAHMUTT.js?v=c5431c96:15962:22)
    at beginWork$1 (chunk-ZSAHMUTT.js?v=c5431c96:19806:22)
    at performUnitOfWork (chunk-ZSAHMUTT.js?v=c5431c96:19251:20)
    at workLoopSync (chunk-ZSAHMUTT.js?v=c5431c96:19190:13)

In general do you agree that when vite first builds the optimized deps that the browser hash before and after restart should be consistent? It feels wrong that the browser hash in memory after the optimizer is finished doesn't match what it just wrote to disk

sapphi-red · 2025-08-22T04:58:12Z

In general do you agree that when vite first builds the optimized deps that the browser hash before and after restart should be consistent? It feels wrong that the browser hash in memory after the optimizer is finished doesn't match what it just wrote to disk

I think it is better to be like that, but not necessarily have to be. So I'm not opposed unless it breaks other behaviors.

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

not necessarily; we see this happen the most frequently in react router SSR mode where the initial document is served and it loads some big modules like react and eventually it's hmr runtime which then loads the vite client

Hmm, that could happen. That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

packages/vite/src/node/optimizer/optimizer.ts

infiton · 2025-08-22T12:53:12Z

That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

yah that makes sense, unfortunately in our case we don't control the load order as it is determined by (1) the frontend framework (react-router v7 in this case) and then (2) our users that can write arbitrary code and our goal is to make the underlying tech as reliable as possible

infiton · 2025-08-22T13:36:12Z

I'm going on vacation for a week, so tagging in my colleague @airhorns to address any comments while I'm away

airhorns · 2025-08-26T17:46:11Z

Just following up here -- happy to make any changes necessary or address comments

Hmm, that could happen. That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

For this, you are right, but I think even if the vite client is the first script loaded on the page, we still can't guarantee that the vite server didn't reboot in between when the page was served and then the client is requested. I think in normal local operation it'd be incredibly unlucky, but in remote development contexts like Github codespaces / codesandbox / Gadget etc, I think the window of opportunity gets bigger.

I am not incredibly familiar with Vite's internals, but AFAICT this shouldn't have much of a negative performance impact, and corrects the bug for these users, so is there a downside to including this fix?

infiton · 2025-09-03T17:10:04Z

back from vacation now so I can respond to any feedback

infiton · 2025-09-08T13:24:58Z

ping @sapphi-red think we are ok to merge this?

sapphi-red · 2025-09-13T16:01:07Z

I'd like another member to take a look.

bluwy

I'm not very familiar with the optimizer flow, but this seem fine to me.

For the new await depsOptimizer.scanProcessing additions, can we add a comment about explaining why we're waiting for processing? I think it's to await for a stable browserHash as it could change?

infiton · 2025-09-17T21:31:17Z

@sapphi-red you feel comfortable to merge?

bluwy · 2025-09-17T23:53:43Z

My comment hasn't been addressed yet. And I'm sure sapphi will merge as soon as he feels ready, there's no need to push as the PR isn't stale yet.

hi-ogawa · 2025-09-18T00:54:28Z

/ecosystem-ci run

pkg-pr-new · 2025-09-18T00:55:18Z

Open in StackBlitz

npm i https://pkg.pr.new/vite@20609

commit: a1d485c

vite-ecosystem-ci · 2025-09-18T02:57:00Z

📝 Ran ecosystem CI on 80d8a72: Open

suite	result	latest scheduled
laravel	❌ failure	❌ failure
unocss	❌ failure	❌ failure
sveltekit	❌ failure	✅ success

✅ astro, analogjs, nuxt, marko, histoire, one, ladle, react-router, rakkas, vite-environment-examples, qwik, storybook, vite-plugin-pwa, quasar, vike, vite-plugin-svelte, vite-plugin-vue, vite-plugin-react, waku, vitepress, vite-plugin-rsc, vuepress, vite-setup-catalogue, vitest, vite-plugin-cloudflare

sapphi-red · 2025-09-18T03:10:10Z

~~Hmm, it seems this change breaks sveltekit's test. That has to be checked before merging as well.~~
sveltekit failed with main branch as well, so the failure is not related to this PR.
https://github.com/vitejs/vite-ecosystem-ci/actions/runs/17817427184/job/50653363205

hi-ogawa

I'm also not sure this will the complete fix for the explained use case, but this change looks okay on its own and as a start.

By searching ?v= injection, I also saw this line for example. Is this code path not relevant or should also await scanProcessing or is it already guaranteed somehow?

vite/packages/vite/src/node/plugins/resolve.ts

Lines 836 to 838 in d8169f0

    
           const versionHash = depsOptimizer.metadata.browserHash 
        
           if (versionHash && isJsType) { 
        
             resolved = injectQuery(resolved, `v=${versionHash}`)

infiton · 2025-09-23T12:52:11Z

hey folks, is there any thing I can do to help get this released?

hi-ogawa · 2025-09-24T00:42:57Z

Btw, have you tested this patch on your platform? or does it require this to be published on npm? FYI, as a preview release, the package made from this PR can be installed like #20609 (comment)

infiton · 2025-09-24T04:39:17Z

Btw, have you tested this patch on your platform? or does it require this to be published on npm? FYI, as a preview release, the package made from this PR can be installed like #20609 (comment)

yah we've been running with this patch on top of version of 6.3.5 for over a month now and it's completely resolved our issue

sapphi-red

I think these two needs to be addressed.

For the new await depsOptimizer.scanProcessing additions, can we add a comment about explaining why we're waiting for processing? I think it's to await for a stable browserHash as it could change?
#20609 (review)

By searching ?v= injection, I also saw this line for example. Is this code path not relevant or should also await scanProcessing or is it already guaranteed somehow?

vite/packages/vite/src/node/plugins/resolve.ts

Lines 836 to 838 in d8169f0

const versionHash = depsOptimizer.metadata.browserHash

if (versionHash && isJsType) {

resolved = injectQuery(resolved, `v=${versionHash}`)

#20609 (review)

infiton · 2025-10-09T23:00:16Z

ok @sapphi-red I believe I have addressed those comments now

packages/vite/src/node/plugins/resolve.ts

…nd persisted metadata When the dev server restarts mid–asset waterfall and loads cached `_metadata.json`, inconsistent `browserHash` values can cause duplicate instances of the same dependency to be loaded (e.g. multiple React copies). This patch sets the `browserHash` eagerly in memory before resolving `scanProcessing`, ensuring both the in-memory metadata and the persisted metadata use the same value.

sapphi-red · 2025-10-17T07:38:18Z

Thanks for the update.

While re-reviewing the PR, I noticed that this fix would have other problems.

If the WebSocket is not connected properly as mentioned in #20609 (comment), Vite won't work properly anyway. I think it's better to show the websocket connection error in the error overlay so that users can notice it instead of this change.

Even if the WebSocket is connected properly due to the client load is done after other scripts (#20609 (comment)), the module graph would be partial and that could cause HMR issues. We need to trigger a reload if the whole page is not served by a single server instance, but I'm not sure if that's possible to do on Vite side.

@patak-dev pointed out that this change essentially makes the scanner blocking, which would revert #7379. If we decide to go with that behavior change, I think it would be better to await the scanner instead of applying the change in this PR.

In addition, the diff ended up being larger than I initially expected, so it's a bit difficult for me to merge this PR into the rolldown-vite side and I prefer to wait until the next major.

Sorry for going back and forth on this.

hi-ogawa · 2025-10-17T09:47:34Z

I recently came across similar errors while working on SSR demo for #20913. I think this is a minimal repro https://github.com/hi-ogawa/reproductions/tree/main/vite-20609-mismatch-but-no-reload to show what I saw. Note that my repro doesn't have anything like "Mid-load restart" and the cause seems clear that it's because @vite/client is loaded too late and connection is not yet available when Vite server sends full reload event.

I wonder if Gadget's scenario is actually not because of their specific setup but it's simply because of @vite/client being loaded too late in React router framework mode. If that's the cause, I think ensuring import "@vite/client" at the top of client entry can help. I think it would be nice to have the concrete reproduction of your setup to understand the situation better. (Also optimizeDeps of SSR framework is a tricky topic too by itself.)

infiton · 2025-10-17T11:25:59Z

@hi-ogawa thanks for the repro I need to see if it’s the exact situation that gadget has, but in your repro are you saying there is a userland fix? Do you mind saying more about how you would do that?

hi-ogawa · 2025-10-17T12:39:29Z

Hmm, actually if you are not seeing "optimized dependencies changed. reloading", the cause of the issue must be different. It's only shows why @vite/client being loaded first might be important for a different reason.

For react router's case, I'm not sure what you would call "user land" solution, but for example, adding <script type="module" src="/@vite/client" async></script> in html head is one way. Another way might be to add import "/@vite/client" to the top of React router's inline bootstrap script which is inside <Scripts /> component https://github.com/remix-run/react-router/blob/64f82f1581bd5e72a9312802c60bb61b9278135a/packages/react-router/lib/dom/ssr/components.tsx#L729

This comment was marked as duplicate.

Sign in to view

sapphi-red added the feat: deps optimizer Esbuild Dependencies Optimization label Aug 21, 2025

This comment was marked as duplicate.

Sign in to view

sapphi-red reviewed Aug 22, 2025

View reviewed changes

packages/vite/src/node/optimizer/optimizer.ts Show resolved Hide resolved

sapphi-red added the p2-edge-case Bug, but has workaround or limited in scope (priority) label Sep 1, 2025

sapphi-red approved these changes Sep 13, 2025

View reviewed changes

sapphi-red changed the title ~~fix(optimize-deps): ensure consistent browserHash between in-memory a…~~ fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata Sep 13, 2025

sapphi-red requested review from bluwy and patak-dev September 13, 2025 15:57

bluwy reviewed Sep 17, 2025

View reviewed changes

vite-ecosystem-ci bot added the trigger: preview label Sep 18, 2025

This comment was marked as duplicate.

Sign in to view

hi-ogawa previously approved these changes Sep 18, 2025

View reviewed changes

sapphi-red requested changes Oct 1, 2025

View reviewed changes

infiton dismissed hi-ogawa’s stale review via 1e2b8af October 9, 2025 22:59

infiton force-pushed the optimize-deps-browser-hash branch from 95807da to 1e2b8af Compare October 9, 2025 22:59

graphite-app bot reviewed Oct 9, 2025

View reviewed changes

packages/vite/src/node/plugins/resolve.ts Show resolved Hide resolved

infiton force-pushed the optimize-deps-browser-hash branch from 1e2b8af to 4b3f01e Compare October 9, 2025 23:28

infiton force-pushed the optimize-deps-browser-hash branch from 4b3f01e to a1d485c Compare October 9, 2025 23:45

	const versionHash = depsOptimizer.metadata.browserHash
	if (versionHash && isJsType) {
	resolved = injectQuery(resolved, `v=${versionHash}`)

Uh oh!

fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

Are you sure you want to change the base?

fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

Conversation

infiton commented Aug 13, 2025

Description

Background

The Problem

Solution

Why This Matters

Uh oh!

infiton commented Aug 18, 2025

Uh oh!

This comment was marked as duplicate.

This comment was marked as duplicate.

This comment was marked as duplicate.

sapphi-red commented Aug 21, 2025

Uh oh!

infiton commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as duplicate.

sapphi-red commented Aug 22, 2025

Uh oh!

Uh oh!

infiton commented Aug 22, 2025

Uh oh!

infiton commented Aug 22, 2025

Uh oh!

airhorns commented Aug 26, 2025

Uh oh!

infiton commented Sep 3, 2025

Uh oh!

infiton commented Sep 8, 2025

Uh oh!

sapphi-red commented Sep 13, 2025

Uh oh!

bluwy left a comment

Choose a reason for hiding this comment

Uh oh!

infiton commented Sep 17, 2025

Uh oh!

bluwy commented Sep 17, 2025

Uh oh!

hi-ogawa commented Sep 18, 2025

Uh oh!

pkg-pr-new bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as duplicate.

vite-ecosystem-ci bot commented Sep 18, 2025

Uh oh!

sapphi-red commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hi-ogawa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

infiton commented Sep 23, 2025

Uh oh!

hi-ogawa commented Sep 24, 2025

Uh oh!

infiton commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sapphi-red left a comment

Choose a reason for hiding this comment

Uh oh!

infiton commented Oct 9, 2025

Uh oh!

Uh oh!

sapphi-red commented Oct 17, 2025

Uh oh!

hi-ogawa commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

infiton commented Oct 17, 2025

Uh oh!

infiton commented Aug 21, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 18, 2025 •

edited

Loading

sapphi-red commented Sep 18, 2025 •

edited

Loading

hi-ogawa left a comment •

edited

Loading

infiton commented Sep 24, 2025 •

edited

Loading

hi-ogawa commented Oct 17, 2025 •

edited

Loading

hi-ogawa commented Oct 17, 2025 •

edited

Loading